---
name: "pg_autoctl create formation"
section: "1"
platform: "linux"
package: "pg-auto-failover-cli"
version: "2.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pg_autoctl create formation"
---

# pg\_autoctl create formation(1)

pg\_autoctl create formation pg\_autoctl create formation - Create a new formation on the pg\_auto\_failover monitor

## NAME

pg\_autoctl create formation - pg\_autoctl create formation

pg\_autoctl create formation - Create a new formation on the pg\_auto\_failover monitor

## SYNOPSIS

This command registers a new formation on the monitor, with the specified kind:

```
usage: pg_autoctl create formation  [ --pgdata --monitor --formation --kind --dbname  --with-secondary --without-secondary ]
--pgdata      path to data directory
--monitor     pg_auto_failover Monitor Postgres URL
--formation   name of the formation to create
--kind        formation kind, either "pgsql" or "citus"
--dbname      name for postgres database to use in this formation
--enable-secondary     create a formation that has multiple nodes that can be
                       used for fail over when others have issues
--disable-secondary    create a citus formation without nodes to fail over to
--number-sync-standbys minimum number of standbys to confirm write
```

## DESCRIPTION

A single pg\_auto\_failover monitor may manage any number of formations, each composed of at least one Postgres service group. This commands creates a new formation so that it is then possible to register Postgres nodes in the new formation.

## OPTIONS

The following options are available to **pg\_autoctl create formation**:

- **--pgdata**

  Location where to initialize a Postgres database cluster, using either **pg\_ctl initdb** or **pg\_basebackup**. Defaults to the environment variable **PGDATA**.

- **--monitor**

  Postgres URI used to connect to the monitor. Must use the **autoctl\_node** username and target the **pg\_auto\_failover** database name. It is possible to show the Postgres URI from the monitor node using the command *pg\_autoctl show uri*.

- **--formation**

  Name of the formation to create.

- **--kind**

  A pg\_auto\_failover formation could be of kind **pgsql** or of kind **citus**. At the moment **citus** formation kinds are not managed in the Open Source version of pg\_auto\_failover.

- **--dbname**

  Name of the database to use in the formation, mostly useful to formation kinds **citus** where the Citus extension is only installed in a single target database.

- **--enable-secondary**

  The formation to be created allows using standby nodes. Defaults to **true**. Mostly useful for Citus formations.

- **--disable-secondary**

  See **--enable-secondary** above.

- **--number-sync-standby**

  Postgres streaming replication uses **synchronous\_standby\_names** to setup how many standby nodes should have received a copy of the transaction data. When using pg\_auto\_failover this setup is handled at the formation level.

  Defaults to zero when creating the first two Postgres nodes in a formation in the same group. When set to zero pg\_auto\_failover uses synchronous replication only when a standby node is available: the idea is to allow failover, this setting does not allow proper HA for Postgres.

  When adding a third node that participates in the quorum (one primary, two secondaries), the setting is automatically changed from zero to one.

## ENVIRONMENT

PGDATA

Postgres directory location. Can be used instead of the **--pgdata** option.

PG\_AUTOCTL\_MONITOR

Postgres URI to connect to the monitor node, can be used instead of the **--monitor** option.

XDG\_CONFIG\_HOME

The pg\_autoctl command stores its configuration files in the standard place XDG\_CONFIG\_HOME. See the *XDG Base Directory Specification*.

XDG\_DATA\_HOME

The pg\_autoctl command stores its internal states files in the standard place XDG\_DATA\_HOME, which defaults to **~/.local/share**. See the *XDG* *Base Directory Specification*.

## AUTHOR

Microsoft

## COPYRIGHT

Copyright (c) Microsoft Corporation. All rights reserved.